<html>
    <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Hammerspoon docs: URLDispatcher</title>
    <style type="text/css">
      a { text-decoration: none; }
      a:hover { text-decoration: underline; }
      th { background-color: #DDDDDD; vertical-align: top; padding: 3px; }
      td { width: 100%; background-color: #EEEEEE; vertical-align: top; padding: 3px; }
      table { width: 100% ; border: 1px solid #0; text-align: left; }
      section > table table td { width: 0; }
    </style>
    <link rel="stylesheet" href="docs.css" type="text/css" media="screen" />
  </head>
  <body>
    <header>
      <h1><a href="./index.html">docs</a> &raquo; URLDispatcher</h1>
      <p>Route URLs to different applications with pattern matching</p>
<p>Download: <a href="https://github.com/Hammerspoon/Spoons/raw/master/Spoons/URLDispatcher.spoon.zip">https://github.com/Hammerspoon/Spoons/raw/master/Spoons/URLDispatcher.spoon.zip</a></p>
<p>Sets Hammerspoon as the default browser for HTTP/HTTPS links, and
dispatches them to different apps according to the patterns defined
in the config. If no pattern matches, <code>default_handler</code> is used.</p>

      </header>
      <h3>API Overview</h3>
      <ul>
        <li>Variables - Configurable values</li>
          <ul>
            <li><a href="#decode_slack_redir_urls">decode_slack_redir_urls</a></li>
            <li><a href="#default_handler">default_handler</a></li>
            <li><a href="#logger">logger</a></li>
            <li><a href="#pat_files">pat_files</a></li>
            <li><a href="#pat_watchers">pat_watchers</a></li>
            <li><a href="#set_system_handler">set_system_handler</a></li>
            <li><a href="#url_patterns">url_patterns</a></li>
            <li><a href="#url_redir_decoders">url_redir_decoders</a></li>
          </ul>
        <li>Methods - API calls which can only be made on an object returned by a constructor</li>
          <ul>
            <li><a href="#dispatchURL">dispatchURL</a></li>
            <li><a href="#start">start</a></li>
          </ul>
      </ul>
      <h3>API Documentation</h3>
        <h4 class="documentation-section">Variables</h4>
          <section id="decode_slack_redir_urls">
            <a name="//apple_ref/cpp/Variable/decode_slack_redir_urls" class="dashAnchor"></a>
            <h5><a href="#decode_slack_redir_urls">decode_slack_redir_urls</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher.decode_slack_redir_urls</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>If true, handle Slack-redir URLs to apply the rule on the destination URL. Defaults to <code>true</code></p>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L30">Source/URLDispatcher.spoon/init.lua line 30</a></td>
              </tr>
            </table>
          </section>
          <section id="default_handler">
            <a name="//apple_ref/cpp/Variable/default_handler" class="dashAnchor"></a>
            <h5><a href="#default_handler">default_handler</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher.default_handler</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Default URL handler (Defaults to <code>&quot;com.apple.Safari&quot;</code>)</p>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><p>Can be a string containing the Bundle ID of an application, or a function
that takes one argument, and which will be invoked with the URL to open.</p>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L21">Source/URLDispatcher.spoon/init.lua line 21</a></td>
              </tr>
            </table>
          </section>
          <section id="logger">
            <a name="//apple_ref/cpp/Variable/logger" class="dashAnchor"></a>
            <h5><a href="#logger">logger</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher.logger</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Logger object used within the Spoon. Can be accessed to set the default log</p>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><p>Example: <code>spoon.URLDispatcher.logger.setLogLevel(&quot;debug&quot;)</code></p>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L99">Source/URLDispatcher.spoon/init.lua line 99</a></td>
              </tr>
            </table>
          </section>
          <section id="pat_files">
            <a name="//apple_ref/cpp/Variable/pat_files" class="dashAnchor"></a>
            <h5><a href="#pat_files">pat_files</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher.pat_files</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Internal variable containing a table where the pattern lists read from files are kept indexed by file name, and automatically updated.</p>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L114">Source/URLDispatcher.spoon/init.lua line 114</a></td>
              </tr>
            </table>
          </section>
          <section id="pat_watchers">
            <a name="//apple_ref/cpp/Variable/pat_watchers" class="dashAnchor"></a>
            <h5><a href="#pat_watchers">pat_watchers</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher.pat_watchers</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Internal variable containing a table where the watchers for the pattern files are kept indexed by file name.</p>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L119">Source/URLDispatcher.spoon/init.lua line 119</a></td>
              </tr>
            </table>
          </section>
          <section id="set_system_handler">
            <a name="//apple_ref/cpp/Variable/set_system_handler" class="dashAnchor"></a>
            <h5><a href="#set_system_handler">set_system_handler</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher.set_system_handler</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>If true, URLDispatcher sets itself as system handler for http requests.</p>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L108">Source/URLDispatcher.spoon/init.lua line 108</a></td>
              </tr>
            </table>
          </section>
          <section id="url_patterns">
            <a name="//apple_ref/cpp/Variable/url_patterns" class="dashAnchor"></a>
            <h5><a href="#url_patterns">url_patterns</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher.url_patterns</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>URL dispatch rules.</p>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><p>A table containing a list of dispatch rules. Rules are evaluated in the
 order they are declared. Each rule is a table with the following structure:
 <code>{ url-patterns, app-bundle-ID-or-function, function, app-patterns }</code></p>
<ul>
<li><code>url-patterns</code> can be: (a) a single pattern as a string, (b) a table
containing a list of strings, or (c) a string containing the path of a
file from which the patterns will be read (if the string contains a valid
filename it's used as a file, otherwise as a pattern). In case (c), a
watcher will be set to automatically re-read the contents of the file
when it changes. If a relative path is given (not starting with a &quot;/&quot;),
then it is considered to be relative to the Hammerspoon configuration
directory.</li>
<li>If <code>app-bundle-ID-or-function</code> is specified as a string, it is
interpreted as a macOS application ID, and that application will be used
to open matching URLs. If it is a function pointer, or not given but
&quot;function&quot; is provided, it is expected to be a function that accepts a
single argument, and it will be called with the URL.</li>
<li>If <code>app-patterns</code> is given, it should be a string or a table containing a
pattern/list of patterns, and the rule will only be evaluated if the URL
was opened from an application whose name matches one of those patterns.</li>
<li>Note that the patterns are <a href="https://www.lua.org/pil/20.2.html">Lua patterns</a>
and not regular expressions.</li>
<li>Defaults to an empty table, which has the effect of having all URLs
dispatched to the <code>default_handler</code>.</li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L69">Source/URLDispatcher.spoon/init.lua line 69</a></td>
              </tr>
            </table>
          </section>
          <section id="url_redir_decoders">
            <a name="//apple_ref/cpp/Variable/url_redir_decoders" class="dashAnchor"></a>
            <h5><a href="#url_redir_decoders">url_redir_decoders</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher.url_redir_decoders</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>URL redirection decoders. Default value: empty list</p>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><p>List containing optional redirection decoders (other than the known Slack
decoder, which is enabled by <code>URLDispatcher.decode_slack_redir_urls</code> to
apply to URLs before dispatching them. Each list element must be a list
itself with a maximum of five elements:</p>
<ul>
<li><code>decoder-name</code>: (String) a name to identify the decoder;</li>
<li><code>decoder-pattern-or-function</code>: (String or Function) if a string is
given, it is used as a <a href="https://www.lua.org/pil/20.2.html">Lua pattern</a>
to match against the URL. If a function is given, it will be called with
arguments <code>scheme</code>, <code>host</code>, <code>params</code>, <code>fullUrl</code>, <code>senderPid</code> (the same
arguments as passed to
<a href="https://www.hammerspoon.org/docs/hs.urlevent.html#httpCallback">hs.urlevent.httpCallback</a>),
and must return a string that contains the URL to be opened. The
returned value will be URL-decoded according to the value of <code>skip-decode-url</code> (below).</li>
<li><code>pattern-replacement</code>: (String) a replacement pattern to apply if a
match is found when a decoder pattern (previous argument) is provided.
If a decoder function is given, this argument is ignored.</li>
<li><code>skip-decode-url</code>: (Boolean, optional) whether to skip URL-decoding of the
resulting string (defaults to <code>false</code>, by default URLs are always decoded)</li>
<li><code>source-application</code>: (String or Table, optional): a pattern or list of
patterns to match against the name of the application from which the URL
was opened. If this parameter is present, the decoder will only be
applied when the application matches. Default is to apply the decoder
regardless of the application.</li>
</ul>
<p>If given as strings, <code>decoder-pattern-or-function</code> and <code>pattern-replacement</code>
are passed as arguments to
<a href="https://www.lua.org/manual/5.3/manual.html#pdf-string.gsub">string.gsub</a>
applied on the original URL.</p>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L35">Source/URLDispatcher.spoon/init.lua line 35</a></td>
              </tr>
            </table>
          </section>
        <h4 class="documentation-section">Methods</h4>
          <section id="dispatchURL">
            <a name="//apple_ref/cpp/Method/dispatchURL" class="dashAnchor"></a>
            <h5><a href="#dispatchURL">dispatchURL</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher:dispatchURL(scheme, host, params, fullUrl, senderPid)</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Dispatch a URL to an application according to the defined <code>url_patterns</code>.</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li>scheme - A string containing the URL scheme (i.e. &quot;http&quot;)</li>
<li>host - A string containing the host requested (e.g. &quot;www.hammerspoon.org&quot;)</li>
<li>params - A table containing the key/value pairs of all the URL parameters</li>
<li>fullURL - A string containing the full, original URL. This is the only parameter used in this implementation.</li>
<li>senderPID - An integer containing the PID of the application that opened the URL, if available (otherwise -1)</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td></td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><ul>
<li>The parameters (follow to the <a href="http://www.hammerspoon.org/docs/hs.urlevent.html#httpCallback">httpCallback</a> specification)</li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L188">Source/URLDispatcher.spoon/init.lua line 188</a></td>
              </tr>
            </table>
          </section>
          <section id="start">
            <a name="//apple_ref/cpp/Method/start" class="dashAnchor"></a>
            <h5><a href="#start">start</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>URLDispatcher:start()</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Start dispatching URLs according to the rules</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td></td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/URLDispatcher.spoon/init.lua#L312">Source/URLDispatcher.spoon/init.lua line 312</a></td>
              </tr>
            </table>
          </section>
  </body>
</html>